---
title: 에이전트
description: Learn more about how to define agents in the OpenAI Agents SDK for JavaScript / TypeScript
---

import { Code } from '@astrojs/starlight/components';
import simpleAgent from '../../../../../../examples/docs/agents/simpleAgent.ts?raw';
import agentWithTools from '../../../../../../examples/docs/agents/agentWithTools.ts?raw';
import agentWithContext from '../../../../../../examples/docs/agents/agentWithContext.ts?raw';
import agentWithAodOutputType from '../../../../../../examples/docs/agents/agentWithAodOutputType.ts?raw';
import agentsAsTools from '../../../../../../examples/docs/agents/agentsAsTools.ts?raw';
import agentWithHandoffs from '../../../../../../examples/docs/agents/agentWithHandoffs.ts?raw';
import agentWithDynamicInstructions from '../../../../../../examples/docs/agents/agentWithDynamicInstructions.ts?raw';
import agentWithLifecycleHooks from '../../../../../../examples/docs/agents/agentWithLifecycleHooks.ts?raw';
import agentCloning from '../../../../../../examples/docs/agents/agentCloning.ts?raw';
import agentForcingToolUse from '../../../../../../examples/docs/agents/agentForcingToolUse.ts?raw';

에이전트는 OpenAI Agents SDK의 주요 기본 구성 요소입니다. **Agent** 는 다음으로 구성된 대규모 언어 모델(LLM)입니다:

- **Instructions** – 모델에게 _자기 정체성_ 과 _응답 방식_ 을 알려주는 시스템 프롬프트
- **Model** – 호출할 OpenAI 모델과 선택적 모델 튜닝 매개변수
- **Tools** – LLM이 작업을 수행하기 위해 호출할 수 있는 함수 또는 API 목록

<Code lang="typescript" code={simpleAgent} title="Basic Agent definition" />

이 페이지의 나머지 부분에서는 모든 Agent 기능을 자세히 설명합니다.

---

## 기본 구성

`Agent` 생성자는 단일 구성 객체를 받습니다. 가장 일반적으로 사용되는 속성은 아래와 같습니다.

| Property        | Required | Description                                                                                                  |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `name`          | yes      | 사람이 읽을 수 있는 짧은 식별자                                                                              |
| `instructions`  | yes      | 시스템 프롬프트(문자열 **또는** 함수 – [Dynamic instructions](#dynamic-instructions) 참조)                   |
| `model`         | no       | 모델 이름 **또는** 사용자 정의 [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 구현             |
| `modelSettings` | no       | 튜닝 매개변수(temperature, top_p 등). 필요한 속성이 최상위에 없다면 `providerData` 아래에 포함할 수 있습니다 |
| `tools`         | no       | 모델이 호출할 수 있는 [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) 인스턴스 배열             |

<Code lang="typescript" code={agentWithTools} title="Agent with tools" />

---

## 컨텍스트

에이전트는 **컨텍스트 타입에 대해 제네릭** 입니다 – 예: `Agent<TContext, TOutput>`. _컨텍스트_ 는 여러분이 생성하여 `Runner.run()` 에 전달하는 의존성 주입 객체입니다. 이 객체는 모든 도구, 가드레일, 핸드오프 등으로 전달되며, 상태 저장 또는 공유 서비스(데이터베이스 연결, 사용자 메타데이터, 기능 플래그 등)를 제공하는 데 유용합니다.

<Code lang="typescript" code={agentWithContext} title="Agent with context" />

---

## 출력 타입

기본적으로 에이전트는 **일반 텍스트**(`string`)를 반환합니다. 모델이 구조화된 객체를 반환하도록 하려면 `outputType` 속성을 지정할 수 있습니다. SDK는 다음을 허용합니다:

1. [Zod](https://github.com/colinhacks/zod) 스키마(`z.object({...})`)
2. JSON‑schema 호환 객체

<Code
  lang="typescript"
  code={agentWithAodOutputType}
  title="Structured output with Zod"
/>

`outputType` 이 제공되면, SDK는 일반 텍스트 대신
[structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 자동으로 사용합니다.

---

## 멀티 에이전트 시스템 설계 패턴

에이전트를 함께 구성하는 방법은 다양합니다. 프로덕션 앱에서 자주 보는 두 가지 패턴은 다음과 같습니다:

1. **Manager(에이전트를 도구로 사용)** – 중앙 에이전트가 대화를 소유하고 도구로 노출된 특화 에이전트를 호출
2. **Handoffs** – 초기 에이전트가 사용자의 요청을 파악한 후 전체 대화를 전문가에게 위임

이 접근 방식은 상호 보완적입니다. 매니저는 가드레일이나 레이트 리밋을 한 곳에서 적용할 수 있게 해주며, 핸드오프는 각 에이전트가 대화의 제어를 유지하지 않고 단일 작업에 집중할 수 있게 해줍니다.

### Manager(에이전트를 도구로 사용)

이 패턴에서는 매니저가 제어를 넘기지 않습니다—LLM이 도구를 사용하고 매니저가 최종 답을 요약합니다. 자세한 내용은 [도구](/openai-agents-js/ko/guides/tools#agents-as-tools) 가이드를 참조하세요.

<Code lang="typescript" code={agentsAsTools} title="Agents as tools" />

### Handoffs

핸드오프에서는 분류 에이전트가 요청을 라우팅하지만, 일단 핸드오프가 발생하면 전문가 에이전트가 최종 출력을 생성할 때까지 대화를 소유합니다. 이는 프롬프트를 짧게 유지하고 각 에이전트를 독립적으로 이해할 수 있게 합니다. 자세한 내용은 [핸드오프](/openai-agents-js/ko/guides/handoffs) 가이드를 참조하세요.

<Code lang="typescript" code={agentWithHandoffs} title="Agent with handoffs" />

---

## 동적 instructions

`instructions` 는 문자열 대신 **함수** 가 될 수 있습니다. 이 함수는 현재 `RunContext` 와 Agent 인스턴스를 받고, 문자열 _또는_ `Promise<string>` 을 반환할 수 있습니다.

<Code
  lang="typescript"
  code={agentWithDynamicInstructions}
  title="Agent with dynamic instructions"
/>

동기와 `async` 함수 모두 지원됩니다.

---

## 수명 주기 훅

고급 사용 사례에서는 이벤트를 수신하여 Agent 수명 주기를 관찰할 수 있습니다. 사용 가능한 항목은 [여기](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/lifecycle.ts)에 나열된 에이전트 훅 이벤트 이름을 참조하세요.

<Code
  lang="typescript"
  code={agentWithLifecycleHooks}
  title="Agent with lifecycle hooks"
/>

---

## 가드레일

가드레일을 사용하면 사용자 입력과 에이전트 출력을 검증하거나 변환할 수 있습니다. `inputGuardrails` 및 `outputGuardrails` 배열을 통해 구성합니다. 자세한 내용은 [가드레일](/openai-agents-js/ko/guides/guardrails) 가이드를 참조하세요.

---

## 에이전트 복제/복사

기존 에이전트의 약간 수정된 버전이 필요하신가요? 완전히 새로운 `Agent` 인스턴스를 반환하는 `clone()` 메서드를 사용하세요.

<Code lang="typescript" code={agentCloning} title="Cloning Agents" />

---

## 도구 사용 강제

도구를 제공해도 LLM이 반드시 호출하는 것은 아닙니다. `modelSettings.tool_choice` 로 도구 사용을 **강제** 할 수 있습니다:

1. `'auto'`(기본값) – LLM이 도구 사용 여부를 결정
2. `'required'` – LLM이 도구를 _반드시_ 호출(어떤 도구를 사용할지는 선택 가능)
3. `'none'` – LLM이 도구를 절대 호출하지 않음
4. 특정 도구 이름, 예: `'calculator'` – LLM이 해당 도구를 반드시 호출

<Code lang="typescript" code={agentForcingToolUse} title="Forcing tool use" />

### 무한 루프 방지

도구 호출 후 SDK는 자동으로 `tool_choice` 를 `'auto'` 로 재설정합니다. 이는 모델이 도구를 반복해서 호출하려는 무한 루프에 빠지는 것을 방지합니다. `resetToolChoice` 플래그 또는 `toolUseBehavior` 를 구성하여 이 동작을 재정의할 수 있습니다:

- `'run_llm_again'`(기본값) – 도구 결과로 LLM을 다시 실행
- `'stop_on_first_tool'` – 첫 번째 도구 결과를 최종 답으로 처리
- `{ stopAtToolNames: ['my_tool'] }` – 나열된 도구 중 하나가 호출되면 중지
- `(context, toolResults) => ...` – 실행을 종료할지 여부를 반환하는 사용자 정의 함수

```typescript
const agent = new Agent({
  ...,
  toolUseBehavior: 'stop_on_first_tool',
});
```

---

## 다음 단계

- [에이전트 실행](/openai-agents-js/ko/guides/running-agents) 방법 알아보기
- [도구](/openai-agents-js/ko/guides/tools), [가드레일](/openai-agents-js/ko/guides/guardrails), [모델](/openai-agents-js/ko/guides/models) 심층 탐구
- 사이드바의 **@openai/agents** 아래 전체 TypeDoc 레퍼런스 살펴보기
